3. Merchant Integration Flow: Card Tokenisation and Tokenised Payments

3.1.3 Tokenisation: Step 1 – Create Transaction Object

Merchants must create a Transaction object that will be encrypted and sent to the Payment Gateway as an HTML form POST.

3.1.3.1 Transaction Object

3.1.3.2 Transaction Object Fields

Table 7. Tokenisation: Step 1 - Transaction Fields
# Field
(Case-Sensitive)		 Required
Mandatory
Optional		 Type Length Description
1. Transaction M N/A N/A The tokenization request transaction object
2. Amount M decimal unrestricted Transaction amount - For Card Verification (TransactionType "03") transaction amount must be a zero value.
3. Currency ^ M string 3 The ISO currency code, e.g. ZAR
4. Password ^ M String <= 350 Merchant password (maximum length 350) as defined by the Payserver service account
5. Username ^ M String <= 50 Merchant username (maximum length 50) as defined by the Payserver service account
6. Identifier M String unrestricted Unique identifier issued by the merchant representing the instance of the request.
Preferably a GUID.
7. TransactionType M String 2 Transaction type can be either "01" (Auth & Settle), or "02" (Auth), or "03" (Card Verification).
8. PayserverAlias ^ M String 255 The Payserver alias name defined for the merchant by VPG
9. Product O N/A N/A An array of one or more products that is being purchased
10. Type O String Recharge type. Airtime or ppd (maximum length 50) [Deprecated]
11. SalesType ^ O String 2 Sales type can be either 00, 01 or 03. [Deprecated]
12. Reference O String <= 50 Recharge MSISDN (maximum length of 50). [Deprecated]
13. ProductCode O String <= 50 Product code defined by the merchant (maximum length of 50)
14. ProductAmount O Decimal unrestricted Product amount defined by the merchant
15. ProductDescription O String <= 500 Product description defined by the merchant.
16. MerchantReference M String <= 50 Reference the merchant includes in the form post to identify the transaction on his system..
17. RequestIdentifier M String <= 50 Included by the merchant in the form post to uniquely identify the transaction on their system.
18. CustomerIdentifier M String <= 250 Included by the merchant in the form post to uniquely identify the customer on their system..
19. MerchantTokenReference O String <= 250 A unique identifier provided by the merchant for instances where they wish to cater for multiple customer subscriptions.
A combination of customeridentifier and merchanttokenreference will create a unique token, and allow a single customer to be able to have multiple subscriptions.
If this field is not passed it will be set to CustomerIdentifier above.
token, and allow a single customer to be able to have multiple subscriptions.
If this field is not passed it will be set to CustomerIdentifier above.
20. MerchantIdentifier ^ M String 36 Unique identifier issued to the merchant by VFS to identify him on VPG.
Adheres to pattern.
21. RecurringAction ^ M String 1 This determines whether the tokenisation request is a:
1 – Subscribe
2 – Update
An update will override the current token or add a new one, while the subscribe will only add a new profile and fail if one already exists.
22. NotifyUrl ^ M String <= 500 This is the end–point to which the asynchronous tokenisation response, will be posted back to the merchant's server, once the bank has responded with the token creation (success or failure).
This is an asynchronous post–back to the merchant. See 3.1.9.2 Tokenisation Response Field Definitions for further detail.
23. FailureUrl ^ M String <= 500 This is the redirect end–point to which payment gateway will respond synchronously, after the payment has been completed unsuccesfully (either Auth or Auth & Settle).
See 3.1.7.1 HTTPS Form Post–Back for further detail.
24. ReturnUrl ^ M String <= 500 This is the redirect end–point to which payment gateway will respond synchronously, after the payment has been completed successfully (either Auth or Auth & Settle).
See 3.1.7.1 HTTPS Form Post–Back for further detail.
25. WebHooks O N/A N/A One or more webhooks to provide asynchronous notifications for the outcome of the credit–card payment back to the merchant.
See 3.1.8 Tokenisation: Step 6 – Asynchronous WebHooks response from VPG for the Payment for further detail.
26. WebHook ^ O N/A N/A The WebHook definition defining the custom template, post–back method and end–point to respond to.
27. Template M String <= 500 A Base64 encoded string of the webhooks template parameters passed by the merchant, to be used for the asynchronous transaction result post–back.
See 3.1.8.2 WebHook Payment Response Template for details on the fields that the merchant can request to be populated in this template.
28. Type M String Restricted to 'get' ' or 'post'
29. Url ^ M String <= 500 This is the end–point that an asynchronous notification for the credit-card payment for the transaction result will be posted to.
See 2.1.1 Transport Layer Security and Firewall Requirements for server–to–server post–back pre–requisites.

3.1.3.3 Transaction Object Schema

For confirmation of the transaction object field data types, length, and whether they are mandatory or not, the following XML schema can be queried.
You can also search this schema online at: https://qa.vodacompaymentgateway.co.za/api/docs/Recurring/

Figure 3. Tokenisation: Step 1 – Transaction Object Schema)

Continue

Return